home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / program / bgui12.lha / bgui.doc < prev    next >
Text File  |  1995-09-23  |  20KB  |  474 lines
  1.  
  2.  
  3. `BGUI' release 1.2
  4. ******************
  5.  
  6. Preface
  7. *******
  8.  
  9.                     `BGUI' release 1.2
  10.                 (C) Copyright 1993-1995    Jaba Development
  11.                 (C) Copyright 1993-1995 Jan van den Baard
  12.                   Written using  DICE v3.0 by
  13.      
  14.                 SNail: Jan van den Baard
  15.                    Bakkerstraat    176
  16.                    3082 HE Rotterdam
  17.                         Holland
  18.      
  19.              Fido: 2:286/407.53  (Jan van.den.Baard)
  20.                    EMail: jaba@grafix.wlink.nl
  21.      
  22.                   EMail is preferred.
  23.            If you must use snail mail then please make it clear
  24.            when you absolutely need an anwser and (don't forget
  25.               this) include enough return postage.
  26.      
  27.                       User Manual
  28.              (C)Copyright 1993-1995 Jaba Development
  29.                          __    __
  30.                         / / /  \
  31.                      __      / / / /\ \
  32.                     _____\ \__/ /_/ /_/ /_____
  33.                    (__________________________)
  34.  
  35.    `BGUI',  (C) Copyright 1993-1995 Jaba Development. All rights reserved. This
  36. program is GiftWare. This means that if you want to use the programs you are
  37. morally obligated to reward the author with a gift that, you think, matches
  38. his efforts. If you cannot think of a gift (come on! be creative ;), a small
  39. financial donation will always be gladly accepted.
  40.  
  41.    I have thought about how to release this package for quite some time. My
  42. initial thought went out to shareware but I soon forgot about this. Since most
  43. of the libraries of this kind seem to be shareware I do not think that many
  44. people like this simply because it's anoying to have to pay for a library if
  45. you had to pay for the application as wel.
  46.  
  47.    To avoid these problems I have decided to release this package as giftware
  48. for people writing freely distributable software. With "freely distributable
  49. software" I mean non-crippeled, free of charge software. Authors who wish to
  50. use `BGUI' in shareware and/or commercial programs must pay for the usage of
  51. `BGUI' before actually using it.
  52.  
  53.    ShareWare and/or commercial usage is `not' allowed without:
  54.  
  55.       1) Prior written permission from the author.
  56.       2) A small finacial donation of US$ 20,-, DM 30,- or HFL 30,-.
  57.       3) A free and registered copy of the product including free updates that
  58.          still make use of the library.
  59.  
  60.    The idea behind this distribution policy is simple. You make money with the
  61. aid of `BGUI'? I want to get my (very humble) share.
  62.  
  63.    This software is not crippeled so when you register it you will not recieve
  64. a key-file or an updated version. Registering simply buys you the right to use
  65. this software in shareware and/or commercial applications.
  66.  
  67.    Resonable, eh?
  68.  
  69. Introduction
  70. ************
  71.  
  72.    `BGUI' is a BOOPSI based shared library contaning a number of BOOPSI
  73. classes.  It allows for easy creation and managing of font sensitive and size
  74. adjustable GUI's on the Amiga. Hmm, where have I read something like this
  75. before..., I hear you say.
  76.  
  77.    YES! This is yet another GUI library. I know there has been a lot of
  78. discussions about the usabillity and neccesity of GUI libraries on the nets
  79. lately. Still, being the ignorant bugger that I am, at some point I felt it
  80. was necessary to write yet another one.
  81.  
  82.    Believe me when I say that `BGUI' was not intended to become a releasable
  83. project. I started coding `BGUI' simply because I was amazed what MUI did
  84. using BOOPSI. Therefore I started coding some BOOPSI classes as a learning
  85. experience.
  86.  
  87.    Hmmm... This is beginning to sound like an excuse... As if I did something
  88. terrible ;)
  89.  
  90.    The point is that, while working on BGUI, I saw many GUI libraries being
  91. released and not one of them really seemed to take off. This made me think
  92. that all this talk about "For every app I run I need to install a different
  93. GUI library" really is bull. Please correct me if I'm wrong but I have yet to
  94. see a program requiring a GUI library (with the exception of MUI ofcourse).
  95.  
  96.    Sure there are a lot available but MUI is the only one which actually seems
  97. to be used by the programmers.
  98.  
  99.    This is the reason for `BGUI'. I have tryed to create a library which does
  100. it's thing simular to MUI eliminating the biggest problems that programmers
  101. seem to have with MUI. Meaning no fancy
  102. background-pen-frame-text-image-whatever settings editor, not a zillion extra
  103. images, no external class libraries etc.
  104.  
  105.    `BGUI' is a single library which can be removed as easely as it can be
  106. installed. It provides an easy way to create and control GUI's without becoming
  107. excessive in what it does.
  108.  
  109.    I guess time will tell if `BGUI' is going to be accepted or not...
  110.  
  111. Features
  112. ********
  113.  
  114.    * Requires at least OS 2.04 (Yes, that is a feature :)
  115.  
  116.    * Extends on the existing system gadgetclass and rootclass.
  117.  
  118.    * Creates completely font sensitive GUI's.
  119.  
  120.    * Supports sizable windows.
  121.  
  122.    * AppWindow support.
  123.  
  124.    * Titled group-frames and seperators.
  125.  
  126.    * Supports OS 3.0 when available.
  127.  
  128.    * Style Guide compliant.
  129.  
  130.    * Keyboard control of most gadget classes.
  131.  
  132.    * Several types of notification to create "self driven" GUI's.
  133.  
  134.    * Easy intergration of third-party classes.
  135.  
  136.    * Easy to make your class work directly with BGUI.
  137.  
  138.    * Object oriented.
  139.  
  140.    * Resonable speed, even with a 68000 processor.
  141.  
  142.    * Relatively small library.
  143.  
  144.    * Classes for easy filerequester and commodity creation.
  145.  
  146.    * Seperate ARexx class including source code.
  147.  
  148. Requirements
  149. ************
  150.  
  151.    `BGUI' requires at least version 2.04 of the operating system. It does `not'
  152. run on 1.3 systems. Are there still people running 1.3?
  153.  
  154.    `BGUI' also requires the following disk-based libraries to operate:
  155.  
  156.    * gadtools.library        (V37)    (menus)
  157.  
  158.    * asl.library        (V37)    (filereq class)
  159.  
  160.    * commodities.library    (V37)    (commodities class)
  161.  
  162.    The following libraries are not required but they will impose on the
  163. functionality of the library when not available:
  164.  
  165.    * locale.library        (V38)    (localized library strings)
  166.  
  167.    * amigaguide.library    (V37)    (On-line help)
  168.  
  169.    * workbench.library         (V37)    (App-window support)
  170.  
  171.    It should not be a problem to use BGUI on a system with 512KByte but a
  172. minimum of 1 Megabyte is suggested as a minimum.
  173.  
  174. Installation
  175. ************
  176.  
  177.    The installation of BGUI is very simple. You can either use the Installer
  178. utility by C= which will install the library for you or you can copy the
  179. `bgui.library' to your LIBS: directory or into a directory you might have
  180. setup for non-system libraries.
  181.  
  182.    Where you put the headers/modules for the language you use is up to you.
  183. Since the different compilers and users use different directory structures I
  184. did not supply a script for you to install these. You'll have to do this by
  185. hand.
  186.  
  187. Read Me
  188. *******
  189.  
  190.    * The bgui.library is a special library in the sence that it is a single
  191.      task library.  This means that `every' task using the library must open
  192.      the library for itself.  The library base pointer may `not' be shared
  193.      between different tasks.
  194.  
  195.      The reason for this is that the library tracks information like window
  196.      bounds etc.  This tracking is done for each individual task.
  197.  
  198.      So if your code spawns a sub-task which needs the library, the sub-task
  199.      code must open the library for itself. It may not share it with the main
  200.      task.
  201.  
  202.    * The object ID's (gadgets and menus) are restricted to the range 1..65535.
  203.      ID's smaller or larger than this are not allowed. This should not be a
  204.      problem :)
  205.  
  206.    * When designing custom classes to work with BGUI please try to keep your
  207.      tag values and method ID's well out of the range of the BGUI tag values
  208.      and method ID's. Using values that conflict with the BGUI values may have
  209.      unexpected results.
  210.  
  211.    * Do not be alarmed when you notice disk-activity when a BGUI requester
  212.      pops up. This is due to the fact that the bgui.library catalog file is
  213.      re-loaded each time BGUI needs it. This makes sure that the language is
  214.      correct if it changed.
  215.  
  216.    * When scrolling a large listview the mouse pointer may move in steps
  217.      rather than smoothly. This is not abnormal behaviour with BOOPSI objects
  218.      because all rendering occures on the input device it's task. Just scroll
  219.      a MultiView window with the scroller and you'll see the same effect.
  220.  
  221.    * The BGUI windowclass depends on the IDCMP_SIZEVERIFY flag. This means
  222.      that the responce to the signals you get have to be as quick as possible.
  223.      If you need to use DOS routines or are unable to call uppon the
  224.      windowclass event handler for a while you need to switch of the
  225.      IDCMP_SIZEVERIFY dependance before you do and back on after you're done.
  226.      There is a tag called WINDOW_NoVerify for this.
  227.  
  228. Keyboard & Mouse
  229. ****************
  230.  
  231.    Most of the BGUI gadget objects can be controlled by the keyboard. Usually
  232. the key that is used to control an object is shown by an underlined character
  233. in the object it's label. The objects can be controlled as follows:
  234.  
  235.    * `Button' - Pressing the key will make the object appear pressed. If you
  236.      release the key the object appears normal again and the application is
  237.      signalled that the object was selected. When you accidentally activated
  238.      the button you can press SHIFT or ESC before releasing the key to cancel
  239.      the selection.
  240.  
  241.    * `Toggle Button' - Pressing the key will toggle the selected state of the
  242.      toggle button.
  243.  
  244.    * `CheckBox' - Pressing the key will toggle the selected state of the
  245.      checkbox object.
  246.  
  247.    * `Prop (Scroller)' - Pressing the key will advance the knob position by
  248.      one page. When you press the key together with SHIFT the knob will backup
  249.      one page. You can reset the knob position when you are dragging the knob
  250.      with the mouse by clicking on the right mouse button.
  251.  
  252.    * `Listview' - Pressing the key will select the next entry in the list
  253.      scrolling the entries when necessary. Pressing the key together with
  254.      SHIFT will select the previous entry. Read only listview objects will
  255.      simply scroll the list forward and backward.
  256.  
  257.    * `Cycle' - Pressing the key will cycle one choise forward. Pressing the
  258.      key together with SHIFT will cycle one choise backward. Selecting the
  259.      gadget with the mouse while holding down the SHIFT key will also make the
  260.      gadget cycle backward. When the cycle gadget was setup to be a popup
  261.      gadget by the application programmer you can click inside the label area
  262.      to pop-up a menu from which you can select the desired item. You can
  263.      recognize a popup gadget by the imagery left of the label area. Normal
  264.      cycle gadgets have a circular arrow here and popup gadgets have a small
  265.      menu here.
  266.  
  267.    * `Slider' - Pressing the key will advance the knob position by one.
  268.      Pressing the key together with shift will decrease the knob position by
  269.      one. You can reset the knob position when you are dragging the knob with
  270.      the mouse by clicking to on the right mouse button.
  271.  
  272.    * `String,Integer' - Pressing the key will simply activate the gadget.
  273.  
  274.    * `Mx' - Pressing the key will select the next button skipping any disabled
  275.      buttons. Pressing the key together with shift will select the previous
  276.      button skipping any disabled buttons. If the Mx object is in tabs mode
  277.      the choises will not stop at the last or first selection but instead it
  278.      will cycle back to the start or the end.
  279.  
  280.    As you can see this behaviour is mostly style guide compliant with some
  281. additional possibilities.
  282.  
  283. Disclaimer
  284. **********
  285.  
  286.    THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED BY
  287. APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
  288. AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS IS" WITHOUT WARRANTY OF ANY
  289. KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  290. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE
  291. ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS WITH YOU.
  292. SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  293. SERVICING, REPAIR OR CORRECTION.
  294.  
  295.    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
  296. ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAMS AS
  297. PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
  298. INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
  299. THE PROGRAMS (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
  300. INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE
  301. PROGRAMS TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
  302. PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  303.  
  304. License
  305. *******
  306.  
  307.    This license applies to the product called `BGUI', a program for the Amiga
  308. computer, published by Jan van den Baard under the concepts of GiftWare, and
  309. the accompanying documentation, example files and anything else that comes
  310. with the original distribution. The term "Program" below, refer to this
  311. product. The term "Author" below, refers to "Jan van den Baard". The license
  312. is addresses as "you".
  313.  
  314.    * You may copy and distribute verbatim copies of the program's executable
  315.      code and documentation as you receive it, in any medium, provided that
  316.      you conspicuously and appropriately publish only the original, unmodified
  317.      program, with all copyright notices and disclaimers of warranty intact
  318.      and including all the accompanying documentation, example files and
  319.      anything else that came with the original.
  320.  
  321.    * You may not copy and/or distribute this program without the accompanying
  322.      documentation and other additional files that came with the original. You
  323.      may not copy and/or distribute modified versions of this program.
  324.  
  325.    * You may not copy, modify, sublicense, distribute or transfer the program
  326.      except as expressly provided under this license.  Any attempt otherwise
  327.      to copy, modify, sublicense, distribute or transfer the program is void,
  328.      and will automatically terminate your rights to use the program under
  329.      this license.  However, parties who have received copies, or rights to
  330.      use copies, from you under this license will not have their licenses
  331.      terminated so long as such parties remain in full compliance.
  332.  
  333.    * By copying, distributing and/or using the program you indicate your
  334.      acceptance of this license to do so, and all its terms and conditions.
  335.  
  336.    * Each time you redistribute the program, the recipient automatically
  337.      receives a license from the original licensor to copy, distribute and/or
  338.      use the program subject to these terms and conditions.    You may not
  339.      impose any further restrictions on the recipients' exercise of the rights
  340.      granted herein.
  341.  
  342.    * You may not disassemble, decompile, re-source or otherwise reverse
  343.      engineer the program.
  344.  
  345.    * You are free to use the programs. If, after an evaluation period of up to
  346.      30 days, you find the programs useful enough to continue using them you
  347.      are morally, not lawfully, obligated to send the author a gift that, you
  348.      think, matches his efforts. Shareware or commercial usage of the programs
  349.      require registering. Please refer to the *note Preface::.  section for
  350.      more information on registering.
  351.  
  352.    * If you wish to incorporate parts of the programs into other programs,
  353.      write to the author to ask for permission. If you want to release your
  354.      programs as being Public Domain, FreeWare or GiftWare you are allowed to
  355.      include a copy of the "bgui.library" without the accompaning
  356.      documentation and files. ShareWare and Commercial distribution of the
  357.      programs is not allowed without prior written permission. Please refer to
  358.      the *note Preface::. section for more information on registering.
  359.  
  360.    * You agree to cease distributing the program and data involved if
  361.      requested to do so by the author.
  362.  
  363.    * You may charge a fee to recover distribution costs. The fee for diskette
  364.      distribution may not be more than the cost to obtain a public domain
  365.      diskette from Fred Fish.
  366.  
  367. Future
  368. ******
  369.  
  370.    This is a list of known bugs and quirks. Please read this before you start
  371. sending me bug reports and suggestions.
  372.  
  373.      `BUG'  = A bug that is still present.
  374.      `SUG'  = A suggestion which might be implemented in the future.
  375.      `REV'  = Revision and/or fine-tuning that still needs to be done.
  376.      `MAY'  = Maybe...
  377.  
  378.    * `BUG' - The layout engine locks up when, due to a bug or hacking, you
  379.      re-size a window smaller than it's minimum as decided by BGUI. Reported
  380.      by Florian Vorberger.
  381.  
  382.    * `BUG' - The infoclass screws up computing it's minimum dimensions when
  383.      the last thing in the text is a command sequence. Should not be a real
  384.      problem since it is bullshit to end a string with a command sequence.
  385.  
  386.    * `BUG' - There seem to be problems when using the textfield.gadget in a
  387.      BGUI context.  The problem is that if you select an object while the
  388.      textfield object is active you get a double message from the clicked
  389.      object. I do not know why this is happening.
  390.  
  391.    * `REV' - `BGUI' gadgets on intuition requesters is `NOT' supported yet.
  392.  
  393.    * `REV' - The commodity class could use some cleaning up. I'm not really
  394.      satisfied with it as it is.
  395.  
  396.    * `REV' - The format of the library and class documentation files suck. I
  397.      should convert them to "real" autodoc format or amigaguide files.
  398.  
  399.    * `REV' - Error reporting. It's OK that a window failed to open or an
  400.      object failed to create but it would be nice to know why. Both numeric
  401.      and textual error descriptions should be made available.
  402.  
  403.    * `REV' - Adding method, conditional and hook notification to the window
  404.      class to. This will allow notification to happen on the application task
  405.      instead of the input.device task.
  406.  
  407.    * `REV' - Work on the menus. For now it is not possible to dynamically add
  408.      items, add notification or help files to the menus. This really sucks.
  409.  
  410.    * `REV' - Try to cut down on the code size. Although, all things
  411.      considering, BGUI is not excessive in size I'de like to see it smaller.
  412.  
  413.    * `MAY' - Letting the window backfill hook optionally make use of the
  414.      preferred workbench window backfill pattern or picture.
  415.  
  416.    * `MAY' - Fonts and images in the info class.
  417.  
  418.    * `MAY' - Add a posibility to "snapshot" window sizes to disk. Should this
  419.      be up to the application programmer? Suggested by Paul Weterings.
  420.  
  421.    * `MAY' - Take the layout engine of BGUI and make a seperate shared/link
  422.      library out of it. This would result in a +/- 10 KByte shared/link
  423.      library with the same functionality as the BGUI layout engine. Maybe this
  424.      will satisfy those people who are always bitching and complaining about
  425.      GUI engine libraries.
  426.  
  427. Thanks To
  428. *********
  429.  
  430.    The author would like to extend a big thank you to the following people for
  431. their valuable help:
  432.  
  433.    Bjorn Reese, Jim Cooper, Jim Karczewski, Keith Christopher, Michael
  434. Wiedmer, Michiel Willems, Magne Oestlyngen, Magnus Enarsson, Martin Bischoff,
  435. Parrish Heywood, Patrick van Beem, Paul Hill, Paul McLachlan, Paul Weterings,
  436. Per Harald Myrvang, Ranulf Doswell, Zachary A Forsyth.
  437.  
  438.    And the people I may have forgotten...
  439.  
  440.    Thanks should also go to:
  441.  
  442.    * Gary Duncan, Heiko Rath and Boris Jakubaschk for giving me permission to
  443.      use their SCSI-2 code for the BGUIPlayer demo program.
  444.  
  445.    * All the folks at `O.I.C'. Obvious Implementations Corporation. This
  446.      software is completely developed using DICE in the registered version and
  447.      later on the commercial version.
  448.  
  449.    * Francesco Devitt for MemLeak. A remarkable simple but very useful tool ;)
  450.  
  451.    * Reinhard Spisser and Sebastiano Vigna for their wonderful Makeinfo which
  452.      was used to generate this AmigaGuide./ASCII documentation.
  453.  
  454.    * Bryce Nesbitt and Michael Sinz for Enforcer. The best bug-hunter for the
  455.      Amiga.
  456.  
  457. Index
  458. *****
  459.  
  460. * Menu:
  461.  
  462. * Disclaimer:                           Disclaimer.
  463. * Features:                             Features.
  464. * Future:                               Future.
  465. * Installation:                         Installation.
  466. * Introduction:                         Introduction.
  467. * Keyboard & Mouse:                     Keyboard & Mouse.
  468. * License:                              License.
  469. * Preface:                              Preface.
  470. * Read Me:                              Read Me.
  471. * Requirements:                         Requirements.
  472. * Thanks To:                            Thanks To.
  473.  
  474.